home *** CD-ROM | disk | FTP | other *** search
/ Amiga News 96 / Amiga News 96.iso / amig_ad_os / makecd_2.2b / goodies / nsdpatch / readme.first < prev    next >
Text File  |  1997-06-02  |  9KB  |  261 lines
  1.  
  2.     $Id: README.FIRST 1.8 1997/03/15 07:59:37 heinz Exp $
  3.  
  4. NSDPatch
  5. ========
  6.  
  7. What is NSDPatch?
  8. -----------------
  9.  
  10. NSDPatch will hook into OS 3.1 (V40) and patch almost arbitrary
  11. types of devices to make them look like NSD compliant devices. With
  12. a configuration file, you can set up NSD like behaviour even for
  13. most devices that were not known to the authors of NSDPatch.
  14.  
  15. NSDPatch also includes some support for trackdisk like devices to
  16. emulate the NSD 64 bit access commands on top of old devices. With
  17. NSDPatch and the AT V43 FFS, you should be able to use partitions
  18. on disks >4GB.
  19.  
  20. NSDPatch also fixes some bugs with certain devices like the V40
  21. mfm.device.
  22.  
  23. NSDPatch will allow you to turn on correct command rejection via
  24. IOERR_NOCMD for devices that would crash otherwise.
  25.  
  26. NSDPatch will optionally try to do some magic for broken SANA2
  27. devices, too.
  28.  
  29. NSDPatch may also be useful for developers of NSD using SW to
  30. simulate different and possibly incomplete NSD environments for
  31. testing.
  32.  
  33. NSDPatch is not intended to replace an NSD upgrade for old devices
  34. forever. It is also not intended to provide for every single NSD
  35. bell and whistle in the specs. It is intended to ease the migration
  36. path and to give some basic NSD capabilities to those who otherwise
  37. couldn't have it at all.
  38.  
  39.  
  40. What is NSD?
  41. ------------
  42.  
  43. NSD is referring to the New Style Device standard as documented on
  44. the Amiga Technologies Amiga Developer CD in the
  45.  
  46.     Amiga_Dev_CD_v1.1:DevInfo/DeviceDevelopment
  47.  
  48. directory. It is intended to provide for clean device usage in the
  49. future.
  50.  
  51. Updates to this standard are available on ftp.amiga.de and it is
  52. probably a good idea to check for them once in a while.
  53.  
  54. If you want more information about NSD, you can also contact the
  55. author of this document at the address mentioned below.
  56.  
  57.  
  58. WARRANTY AND LEGALES
  59. --------------------
  60.  
  61. WARRANTY: None whatsoever. Standard disclaimer applies.
  62.  
  63. LEGALESE: FREELY REDISTRIBUTABLE, NOT PD! CHANGES NOT ALLOWED!
  64.  
  65.  
  66. Installation
  67. ------------
  68.  
  69. There is an Installer-Script "Install" included, that does a quick
  70. installation and setup of NSDPatch, including its configuration. If
  71. you don't want that automatic installation, you can read below
  72. about the details of a custom installation.
  73.  
  74. First, take a look at the demonstration configuration file
  75. NSDPatch.cfg. It describes in detail all the available
  76. configuration options and contains all the entries for a basic OS
  77. 3.1 based system. When you have looked it over and want to boldly
  78. go where (almost) no one has gone before, proceed like this:
  79.  
  80.   A. BASIC INSTALLATION
  81.  
  82.     1. Make a copy of the file, and and place it preferrably into
  83.        SYS:DEVS, with SYS: referring to your boot volume.
  84.  
  85.     2. Copy NSDPatch into SYS:C.
  86.  
  87.     3. Check the configuration file in SYS:DEVS for any devices
  88.        that you don't want to have patched and comment out these
  89.        lines. Add entries for any special devices. Please report
  90.        configuration lines for 3rd party devices to the author.
  91.        Keep another copy of your changes in case of future
  92.        automatic updates. Use NSDQuery to check if a device already
  93.        supports NSD.
  94.  
  95.     4. Place a line like this into your SYS:S/Startup-Sequence
  96.        immediately after SetPatch is called:
  97.  
  98.         NSDPatch PCF DEVS:NSDPatch.cfg
  99.  
  100.        It is very important that this line is added immediately
  101.        after SetPatch. That is why NSDPatch must be placed into
  102.        SYS:S/Startup-Sequence and not in User-Startup.
  103.  
  104.        Alternatively, you can run the included Installer-Script
  105.        "Install", which does a quick installation of NSDPatch.
  106.  
  107.     5. Reboot and watch the messages that are output by NSDPatch.
  108.        These messages tell you what NSDPatch does. If you can't
  109.        agree with them in some way, go back to 3.
  110.  
  111.     6. Try NSDQuery on patched devices to check if everything was
  112.        successful. If you encounter problems that can't be fixed
  113.        by going back to 3., check B and C.
  114.        Please report all problems to the author with the device
  115.        names and versions that cause the problems!
  116.  
  117.     7. Assuming there were no problems, add the "QUIET" option to
  118.        the NSDPatch line in your startup.
  119.  
  120.     8. That's it. This is the end of a successful installation.
  121.  
  122.  
  123.   B. SPECIAL INSTALLATIONS
  124.  
  125.     1. You may have 3rd party devices which don't support
  126.        IOERR_NOCMD correctly. This means that the driver will not
  127.        reject unknown commands with IOERR_NOCMD, but either crash
  128.        or do very strange things instead. In that case, use the
  129.        IOERRNOCMD option for the respective patch configuration. No
  130.        devices of this type can be named at this time. If you want
  131.        to boot from such a device, read the description of the
  132.        RDBUNIT option carefully. If you encounter such a device,
  133.        please report it to the author.
  134.  
  135.     2. You may have a trackdisk like device supporting the 3rd
  136.        party TD64 command set. In that case, use the TD64 option
  137.        for the respective patch configuration. By using the
  138.        TD64 option, the general NSD 64 bit commands will be
  139.        rerouted to the already existing TD64 functionality instead
  140.        of being emulated via HD_SCSICMD. Current Guru-ROM's and
  141.        Phase 5 SCSI devices may support TD64. No exact versions can
  142.        be named at this time.
  143.  
  144.     3. NSDPatch can be invoked multiple times to install more
  145.        patches. Installed patches cannot be changed without a
  146.        reboot.
  147.  
  148.     4. You can invoke NSDPatch with a config file that doesn't
  149.        actually patch anything but only uses the ACTIVATE and
  150.        RDBUNIT features of NSDPatch. This is considered a positive
  151.        side effect of the NSDPatch design.
  152.  
  153.     5. You may have a SANA2 device that can't handle a NULL
  154.        ios2_BufferManagement pointer on startup. If you have one of
  155.        those, you'll get enforcer hits with most likely an access
  156.        to address 0 first on a check with NSDQuery. In that case,
  157.        specify the SANA2MAGIC option in the configuration.
  158.  
  159.  
  160.   C. TROUBLE SHOOTING
  161.  
  162.     1. In the unlikely case that NSDPatch crashes your machine on
  163.        the first invocation, you may want to
  164.  
  165.         - reduce the configuration file to a single line, e.g. for
  166.           parallel.device to make testing easier.
  167.  
  168.         - check your system for any virus
  169.  
  170.     2. If you are not sure if a patch was successful, use the
  171.        NSDQuery tool to check up on that device.
  172.  
  173.     3. If multiple calls to NSDQuery while a device is in memory
  174.        reveal that the reported io_Device value changes for every
  175.        invocation, NSDPatch will not be able to patch this device
  176.        for any openers that opened the device before NSDPatch was
  177.        installed. This is not a bug in NSDPatch.
  178.  
  179.     4. If NSDQuery behaves strangely on any device, patched or not,
  180.        please report the exact circumstances, including all
  181.        configuration and version information for your Amiga.
  182.  
  183.  
  184. Contact
  185. -------
  186.  
  187. If you have any comments on NSDPatch, please send them to:
  188.  
  189.     Heinz Wrobel
  190.     Karlstr.16
  191.     82131 Gauting
  192.     Germany
  193.     <heinz@hwg.muc.de>
  194.  
  195.  
  196. Implementation
  197. --------------
  198.  
  199. This may not be very interesting to most readers as it hints at
  200. some technical details. NSDPatch hooks itself into the exec.library
  201. OpenDevice() function. It will patch any opened device that should
  202. be patched and "preprocess" requests sent to it. This way, the user
  203. software sees an NSD device and the device itself will not have to be
  204. reworked in strange device specific ways. Devices patched like this
  205. can still be expunged and reloaded freely. The permanent NSDPatch
  206. footprint in memory is about 3KB plus memory for configuration data
  207. for each device to be patched. NSDPatch does not need to be started
  208. in the background and it does not use any ugly SegList splitting
  209. hacks or similar stunts. NSDPatch should also be compatible to all
  210. debugging tools.
  211.  
  212.  
  213. History
  214. -------
  215.  
  216. 43.8
  217.     - Reduced stack usage during OpenDevice() patch by about 32
  218.       bytes. The patch needs about 68 bytes now during OpenDevice().
  219.     - The SANA2MAGIC did not work very well. There was a problem in
  220.       handling paths. So it often did not even get activated.
  221.  
  222. 43.7
  223.     - There was a bug in the Version/Revision recognition.
  224.       NSDPatch patched too much at times. This should not have
  225.       hurt, though.
  226.     - Reduced processing time in OpenDevice() a little.
  227.     - Mixing different versions of NSDPatch should not cause any
  228.       harm now.
  229.     - Added new PatchInfo option that tells you about NSDPatch
  230.       activities. Note: This option is more of a debugging hack!
  231.     - More patch lines.
  232.  
  233. 43.6
  234.     - Now supports LVO's that can't normally be SetFunction()'ed.
  235.     - Now supports version specific patches correctly. The override
  236.       general patches.
  237.     - Now supports special SANA2MAGIC for callback handling of old
  238.       devices.
  239.     - Now checks the default patch file DEVS:NSDPatch.cfg
  240.       automatically, if none has been specified.
  241.     - The config file is no longer named v40.nsdpatchcfg. It now
  242.       already has the default name and also has a C= version
  243.       string.
  244.  
  245. Acknowledgements
  246. ----------------
  247.  
  248. Some were very directly involved in thinking up and testing
  249. NSDPatch. Here is a list in no particular order:
  250.  
  251.     Olaf Barthel
  252.     Bernhard Möllemann
  253.     Michael van Elst
  254.     Angela Schmidt
  255.     Klaus Burkert
  256.     Joanne Dow
  257.  
  258. Thank you.
  259.  
  260. Heinz Wrobel
  261.